---
title: Environment variables
description: How to configure Hollo using environment variables.
---

import { Aside, Badge } from '@astrojs/starlight/components';

Hollo is configured using environment variables.  You can set them in an *.env*
file in the root directory of the project, or you can set them using Docker's
`-e`/`--env` option or Railway's environment variables.


Basic settings
--------------

### `PORT` <Badge text="Optional" /> <Badge text="Unused in Railway" variant="tip" />

The port number to listen on.  3000 by default.

### `BIND` <Badge text="Optional" /> <Badge text="Unused in Railway" variant="tip" />

The address to listen on. Must be a valid IP address or `localhost`.

### `DATABASE_URL` <Badge text="Unused in Railway" variant="tip" />

The URL of the PostgreSQL database, e.g.,
`postgresql://hollo:password@localhost/hollo`.

### `SECRET_KEY` <Badge text="Unused in Railway" variant="tip" />

The secret key for securing the session. Must be at least 44 characters long.
You can generate a random secret key using the following command:

~~~~ sh frame="none"
openssl rand -hex 32
~~~~

### `TZ` <Badge text="Optional" />

The time zone of the application.  It has to be a valid time zone identifier,
e.g., `UTC`, `America/New_York`, `Asia/Tokyo`.

`UTC` by default.

### `BEHIND_PROXY` <Badge text="Optional" /> <Badge text="Unused in Railway" variant="tip" />

Set this to `true` if Hollo is behind a reverse proxy.  If you place the Hollo
behind an L7 load balancer (you usually should do this), turn this on.

Turned off by default.

<Aside>
  With this option, Hollo will trust the `X-Forwarded-For`, `X-Forwarded-Proto`,
  and `X-Forwarded-Host` headers from the reverse proxy.  This is important for
  security reasons.
</Aside>

### `ALLOW_PRIVATE_ADDRESS` <Badge text="Optional" />

Setting this to `true` disables SSRF (Server-Side Request Forgery) protection.

Turn on to test in local network.

Turned off by default.

<Aside>
  Turning on this option is dangerous security-wise.  Only use this option in
  a trusted environment and never in production.
</Aside>


Additional features
-------------------

###  `HOME_URL` <Badge text="Optional" />

If present, the home page will redirect to this URL.  If not set, the home page
will show the list of accounts on the instance.

### `REMOTE_ACTOR_FETCH_POSTS` <Badge text="Optional" />

The number of recent public posts to fetch from remote actors when they are
encountered first time.

`10` by default.

### `TIMELINE_INBOXES` <Badge text="Optional" />

Setting this to `true` lets your timelines work like inboxes: all posts visible
to your timeline are physically stored in the database, rather than being
filtered in real-time as they are displayed.  This is useful for relatively
larger instances with many incoming posts.

As of Hollo 0.4.0, it is experimental and may have several bugs, but it is
epxected to be the default behavior in the future after it is stabilized.

Turned off by default.

### `ALLOW_HTML` <Badge text="Optional" />

Setting this to `true` allows raw HTML inside Markdown, which is used for
formatting posts, bio, etc.  This is useful for allowing users to use broader
formatting options outside of Markdown, but to avoid XSS attacks, it is still
limited to a subset of HTML tags and attributes.

Turned off by default.


Logging and debugging
---------------------

### `LOG_LEVEL` <Badge text="Optional" />

The log level for the application.  `debug`, `info`, `warning`, `error`, and
`fatal` are available.

`info` by default.

### `LOG_QUERY` <Badge text="Optional" />

Set this to `true` to log SQL queries.

Turned off by default.

### `LOG_FILE` <Badge text="Optional" />

The path to the log file.  Unlike console output, the log file is written in
JSON Lines format which is suitable for structured logging.

### `SENTRY_DSN` <Badge text="Optional" />

The DSN of the Sentry project to send error reports and traces to.


Asset storage
-------------

### `DRIVE_DISK`

The disk driver used by Hollo to store blobs such as avatars, custom emojis,
and other media.

Valid values are `fs` (local filesystem) and `s3` (S3-compatible object storage).

Defaults to `s3` for backward compatibility, but it is recommended to explicitly
configure the driver as the default value will be removed in the future.

See the [FlyDrive docs] for details about the drivers.

<Aside type="caution">
  If you change the `DRIVE_DISK` and related settings of a running Hollo during
  production, existing files are not moved; only new files are stored according
  to the new settings.

  Also, keep in mind that existing files will still be served according to the
  old settings, so if you change `S3_BUCKET`, for example, they will still be
  served from the old bucket and should not be deleted.
</Aside>

[FlyDrive docs]: https://flydrive.dev/docs/drive_manager

### `STORAGE_URL_BASE`

The public URL base of the asset storage, e.g.,
`https://media.hollo.social`.

When using `DRIVE_DISK=fs`, you should set this to serve local filesystem files
via web access, typically in the format `https://<host>/assets`, e.g.,
`https://hollo.example.com/assets`.

<Aside type="caution">
  - HTTPS is required in production environments.
  - Must be publicly accessible for federation to work correctly.
  - Recommend using a `CNAME`d domain rather than the actual domain of an object
    storage for flexibility.
</Aside>

### Local filesystem settings

#### `FS_STORAGE_PATH` <Badge text="Required with FS driver" variant="note" />

The path in the local filesystem where blob assets are stored, e.g.,
`/var/lib/hollo`.

<Aside>
  - Directory must exist and be writable by the Hollo process.
  - Recommended permissions: 755 for directories, 644 for files.
  - Ensure sufficient storage capacity for your use case.
  - Regular backups are strongly recommended.
  - When using Docker, ensure the path is properly mounted.
</Aside>

### S3-compatible object storage settings

<Aside>
  These settings are only required when `DRIVE_DISK=s3`.

  Ensure your AWS IAM policy grants the following permissions:

  - `s3:PutObject`
  - `s3:GetObject`
  - `s3:DeleteObject`
  - `s3:ListBucket`
</Aside>

#### `S3_REGION` <Badge text="Required with S3 driver" variant="caution" />

The region of the S3-compatible object storage, e.g., `us-east-1`.  On some
non-S3 services, this can be omitted.

#### `S3_BUCKET` <Badge text="Required with S3 driver" variant="caution" />

The bucket name of the S3-compatible object storage, e.g., `hollo`.

#### `S3_ENDPOINT_URL` <Badge text="Required with S3 driver" variant="caution" />

The endpoint URL for S3-compatible object storage, e.g.,
`https://s3.us-east-1.amazonaws.com`.

#### `S3_FORCE_PATH_STYLE` <Badge text="Optional" />

Whether to force path-style URLs for S3-compatible object storage.  `true` to
turn on, `false` to turn off.  Useful for non-AWS S3-compatible services.
Turned off by default.

#### `AWS_ACCESS_KEY_ID` <Badge text="Required with S3 driver" variant="caution" />

The access key for S3-compatible object storage.

#### `AWS_SECRET_ACCESS_KEY` <Badge text="Required with S3 driver" variant="caution" />

The secret key for S3-compatible object storage.
